Integration Guide Universal Robots PolyScope X BPS 1.12 (URCap)

This guide describes how to integrate Universal Robots controllers with PolyScope X with Bin Picking Studio (BPS) 1.12 by using the Photoneo Bin Picking Studio URCap (version 1.12.1). You install the URCap once on each robot controller. It adds a Photoneo settings page and ten BPS program nodes to the teach pendant, so you build your program from program nodes instead of script nodes.

The same Robot module is also available as a URScript library without a URCap. See Integration Guide Universal Robots PolyScope X BPS 1.12.

Note

For the general concept of the communication, see the Robot communication overview. The supported versions of all Robot modules are listed in the Robot module support matrix.

1. Prerequisites

The Robot module is delivered as the URCap file bin-picking-studio-1.12.1.urcapx and a set of .urpx example programs. You install the URCap once on each robot controller. It adds:

• the Photoneo Bin Picking Studio settings page on the Application tab. It holds the vision controller address, the trajectory motion parameters and the gripper outputs. From these settings, the URCap adds the photoneo_common_X.script library, the customer definitions, the gripper functions and the connect call to the beginning (preamble) of every program.

• ten BPS program nodes in the Toolbox. Each node generates one or more pho_* requests.

Note

You do not paste anything into Before Start and you do not create gripper functions manually. The URCap generates the two script blocks and the five gripper functions from the settings page.

Before you start, make sure that your system meets these requirements:

• A Universal Robots e-Series robot with PolyScope X system software

• PolyScope X 10.12.1 or higher

• A free Ethernet port on the robot controller for the connection to the vision controller

• The Real-Time Data Exchange (RTDE) interface enabled on the robot controller (see section 2.2)

• A USB flash drive to transfer the .urcapx URCap and the .urpx example programs to the robot controller

• A vision controller with Bin Picking Studio 1.12

• A Bin Picking Studio solution with at least one calibrated vision system, a configured environment and a configured grasping method

• A MotionCam-3D for the dynamic MultiView (Instant Meshing) example. All other examples work with any supported Photoneo 3D sensor.

Note

This guide does not cover PolyScope 5 and CB-Series controllers. For them, use the separate Robot module for PolyScope 5, which is not a URCap. See Integration guide for robots by Universal Robots.

Note

The URCap contains the same library as the script delivery and sends the same 24-byte brand ID, UNIVERSAL_ROBOTS/v1.12.0. For the vision controller, a robot programmed with the URCap and a robot programmed with the script library are the same.

To check the system version on your robot, go to Main Menu → About:

The PolyScope X version is shown on the first line (Software):

2. Robot Controller Setup

2.1 Network Configuration

First, set the IP address of the robot controller port that you use for the connection to the vision controller. Go to Main Menu → Settings:

Scroll down to Connection → Network. The network settings are password protected. Press Unlock and enter the administrator password. Select Static as the network method and enter the IP address and the subnet mask of the robot controller. This guide uses IP address 192.168.1.2 and subnet mask 255.255.255.0.

Click Apply Configuration, then click Lock and Close to confirm the changes.

Note

The subnet mask 255.255.255.0 is the same as a 24-bit subnet mask (/24). For other combinations, see this table: https://dnsmadeeasy.com/support/subnet

Example of a matching network configuration on the vision controller side:

• Vision controller IPv4 address: 192.168.1.1 / 24

• Robot controller IPv4 address: 192.168.1.2 / 24 (as configured in the previous step)

You can also use the Test Connection button on the Network page of the vision controller to ping the robot controller.

Based on the result of the test (ping command), a Robot Available or Robot Unavailable message is shown. If the robot is unavailable, check the cables and the network configuration.

Note

Enter the vision controller address (192.168.1.1 in this guide) in the IP address field of the Photoneo settings page (section 3.1). The URCap stores it in IP_ADDRESS and connects to it at the start of every program.

2.2 Enabling Real-Time Data Exchange (RTDE)

The vision controller reads the robot state (joint positions and TCP pose) directly from the robot controller through the Real-Time Data Exchange (RTDE) interface. It needs this data for calibration, hand-eye scanning and robot visualization. No Robot State Server program runs on the robot.

Go to Main Menu → Settings → Security → Services and make sure that Real-Time Data Exchange (RTDE) is enabled. The service uses port 30004.

Note

The Services page is also password protected. Press Unlock and enter the administrator password before you change an interface.

2.3 Installing the Bin Picking Studio URCap

The URCap is one file, bin-picking-studio-1.12.1.urcapx. Copy it to a USB flash drive and plug it into the USB port of the teach pendant or of the robot controller. Then go to Main Menu → System Manager:

In the left column of the System Manager, open the URCaps page and press + URCap. Select bin-picking-studio-1.12.1.urcapx on the USB drive. The teach pendant asks you to confirm the installation.

Warning

Installing or uninstalling a URCap reloads the system. The confirmation dialog tells you this. Save your work before you confirm, and do not install a URCap while a program is running.

After the reload, Bin Picking Studio (developer Photoneo, version 1.12.1) is listed on the URCaps page with its contact, copyright and license information. To remove the URCap, use Uninstall URCap on the same page.

Note

The URCap is installed on the robot controller and does not depend on a program. It is not part of a .urpx file and is not copied with a program. A program that uses BPS nodes does not open correctly on a robot without the URCap. The teach pendant shows these lines as a missing contribution. Install the URCap first, then import the programs.

2.4 Loading the Example Programs

These example programs are delivered with the URCap. They are described in section 3.8.

• pho_main_basic_urc.urpx

• pho_main_basic_hand_eye_urc.urpx

• pho_main_basic_multi_vs_urc.urpx

• pho_main_change_bb_urc.urpx

• pho_change_enviroment_urc.urpx

• pho_main_change_solution_urc.urpx

• pho_main_get_object_pose_urc.urpx

• pho_main_get_status_urc.urpx

• pho_main_reuse_scan_urc.urpx

• pho_multiview_static_urc.urpx

• pho_multiview_dynamic_urc.urpx

• pho_calibration_basic_urc.urpx

• pho_calibration_auto_urc.urpx

• pho_calib_basic_hand_eye_urc.urpx

Copy the .urpx files to a USB flash drive and go to Main Menu → System Manager. Press + Program, then Import Program, and select the example programs on the USB drive:

After the import, the example programs are listed on the Programs page of the System Manager. You can open them from there:

Note

A .urpx file contains a program and its application, and the Photoneo settings are part of the application. When you import an example, you also import the settings saved with it: vision controller 192.168.1.1, vision system 1, the default motion parameters and the gripper outputs of the example. After every import, check the settings page against your cell (section 3.1).

Note

PolyScope X does not keep robot programs as files in a /programs directory like PolyScope 5. Programs are stored in an internal application store. You cannot transfer them with scp or an FTP client. Import them from external media in the System Manager, as described above.

Note

A PolyScope X program name can have a maximum of 30 characters. A longer name is rejected at import with the error “Program name is too long”, and the program does not load. Keep the names of renamed copies short. The longest example name in this delivery has 28 characters.

SSH access to the robot controller is available for diagnostics. It is disabled by default. To enable it, go to Main Menu → Settings → Security → Secure shell. There you set the port, the authentication method and the authorized keys.

2.5 Tool (TCP) Setup

Warning

Scan requests temporarily override the active TCP. The library sets the TCP to the tool flange, sends the request and then restores the previous TCP, so that the vision controller reads the flange pose over RTDE. During this short time, get_actual_tcp_pose() called from a parallel thread can return the flange pose and not the pose of your tool.

Bin Picking Studio works with a zero TCP. Set all TCP values to zero, because Bin Picking Studio compensates for the gripper geometry when it plans a trajectory. In the left panel, go to Application → End Effectors:

Make sure that the Tool_flange end effector has zero position and orientation values. This end effector must be active when the program runs.

Note

Check which TCP is active when you program your own motions. A taught waypoint is a pose of the active TCP. If you teach a waypoint with one end effector and run it with another one, the robot moves to a different position.

2.6 Robot State and Robot Pose Visualization

The UR Robot module has no Robot State Server program. When the RTDE service on the robot is enabled, the vision controller connects to RTDE port 30004 and reads the current joint positions and the Cartesian TCP pose. Nothing has to be started on the robot. Bin Picking Studio uses this data for robot visualization, for calibration and for all hand-eye scan requests.

The robot state is also useful for first configuration checks. For example, you can show the current robot pose on the Environment page with the Robot module motion mode:

To check that the correct zero tool pose is reported, start the calibration, switch from the Texture tab to the Verification tab and enable Tool Pose (robot controller) in the Axis menu. The frame marker must be in the center of the flange, with the Z axis pointing down. It must be identical to the Tool0 (robot model) frame.

3. Robot Module

Note

We strongly recommend that you read the Photoneo robotic API before this section.

With the URCap installed, a Bin Picking Studio program consists of two parts: the Photoneo Bin Picking Studio settings page, which you configure once on each robot controller, and the BPS program nodes, which you insert into the program tree from the Toolbox.

The settings page adds this code to the preamble of every program, in this order:

1. photoneo_common_X.script - the request library, exactly as delivered for the script variant

2. the customer definitions - pho_bin_picking, pho_bin_picking_simple, pho_execute_trajectory and execute_gripper, exactly as in the script example programs

3. the motion parameters of section 3.1.2, as the ten-element arrays that the customer definitions use

4. the functions gripper_attach, gripper_detach and gripper_user_1 to gripper_user_3, generated from the gripper table of section 3.1.3

5. the global variables IP_ADDRESS and VISION_SYS_ID, pho_enable_debug() if Debug is on, and then pho_wait_for_server(IP_ADDRESS, <port>, <attempts>)

Note

Because the connect call is in the preamble, it runs at the start of every program. pho_wait_for_server closes the socket first and then opens it again, so a restarted program reconnects cleanly.

3.1 Photoneo Settings Page

Open the settings page on the Application tab of the teach pendant under Photoneo Bin Picking Studio. It has three sections: Vision Controller, Trajectory motion and Gripper outputs.

3.1.1 Vision Controller

Setting	Default	Meaning and generated code
IP address	192.168.1.1	Address of the vision controller. Stored in IP_ADDRESS and passed to pho_wait_for_server.
Port	11003	Port of the Action Request Server. Second argument of pho_wait_for_server.
Attempts	1	Number of connection attempts before the library reports PHO_COM_FAILURE (3) and stops the program.
Vision System	1	Vision system used by the program nodes that are set to Default. Stored in VISION_SYS_ID.
Camera	Fixed	Robot-mounted: the Trigger scan only mode of the BPS Scan node sends the flange pose with the request. The mounting belongs to the cell, not to one program line, so it is set here.
Debug	Off	On adds pho_enable_debug() to the preamble. The library then writes every request, received pose and trajectory segment to the log with textmsg.

3.1.2 Trajectory Motion

Bin Picking Studio plans up to ten trajectory segments for each pick. The customer definitions hold one motion value for each segment. The settings page holds one value for each parameter, and the preamble repeats it for all ten segments.

pho_execute_trajectory selects how each segment is executed from the number of joint waypoints in the segment:

• Streamed - for segments with three or more waypoints. This is the normal case with path planning enabled. The robot follows a smooth curve through the planned waypoints, limited by Trajectory speed and Trajectory acceleration. A new servoj target is sent in every control cycle. The curve never goes beyond a waypoint, and the speed does not depend on how far apart the waypoints are. Where a CNT segment flows into the next one, the robot keeps moving and slows down only as much as the change of direction requires.

• movej - for segments with only two waypoints (path planning off, or a coarse linear sampling). It uses Acceleration, Velocity, Segment time and Blend.

At the end of a FINE segment (for example, the grasp), the robot holds the last waypoint until it is there and at rest. Only then is the gripper command executed.

Setting	Default	Meaning
Trajectory speed	1.0	pho_stream_vel - maximum joint speed along a planned trajectory (rad/s). This is the main speed setting with path planning enabled.
Trajectory acceleration	2.0	pho_stream_acc - maximum joint acceleration along a planned trajectory (rad/s²)
Acceleration	1.4	pho_acc - joint acceleration of a movej segment (rad/s²). Ignored when Segment time is above 0.
Velocity	2.0	pho_vel - joint velocity of a movej segment (rad/s). Ignored when Segment time is above 0.
Blend	0.02	pho_blend - blend radius of a movej segment (m)
Segment time	0	pho_time - if above 0, the movej segment takes this time (s), and Acceleration and Velocity are ignored

Note

For the first run, keep the default values and use the Speed slider on the teach pendant to slow down the robot. When the cycle works, increase Trajectory speed and Trajectory acceleration.

Note

The servoj settings behind the streamed execution (lookahead, gain) and the FINE settling tolerances are not on the settings page on purpose. The customer definitions keep them at tested values. The old execution of version 1.12.0, one servoj for each waypoint, is still in the customer definitions as PHO_EXEC_SERVOJ, for support use only.

Warning

Be careful with the blend radius. If a waypoint is inside the blend radius of the previous or the next waypoint, the robot does not move to this waypoint. This is a problem for precise waypoints such as the grasp. Always keep the blend radius smaller than the distance between the waypoints.

Note

One value applies to all ten segments. To give one segment its own value, for example a slower Approach to Grasp segment, add a Script node at the start of the program that changes one array element, for example pho_stream_vel[1] = 0.5.

3.1.3 Gripper Outputs

The grasping method in Bin Picking Studio defines which gripper command is requested at which waypoint of the trajectory. execute_gripper calls one of five gripper functions for this command. The gripper table generates these five functions from a digital output, a value and a settle time:

Column	Default	Meaning
Action	Attach, Detach, User 1 to User 3	Gripper command that the vision controller requests at a waypoint. Attach and Detach come from the grasping method. You can assign User 1 to User 3 freely.
Output	Controller DO for Attach and Detach, None for User 1 to 3	Type of output. Controller DO generates set_standard_digital_out, Tool DO generates set_tool_digital_out and None generates an empty function. An unused command still needs its function, because execute_gripper calls it.
Number	0	Output number on the robot controller or on the tool flange
Value	High for Attach, Low for Detach	Value to which the output is set
Settle	300 ms for Attach and Detach, 0 ms for User 1 to 3	Wait time after the output is set, so that the gripper acts before the next trajectory segment starts. Generated as sleep.

The defaults above apply to a new settings page. An imported example program brings its own values (section 2.4).

The gripper commands and the functions that execute_gripper calls:

Gripper command	Meaning	Calls
1	Attach	gripper_attach()
2	Detach	gripper_detach()
3, 4, 5	User 1, User 2, User 3	gripper_user_1(), gripper_user_2(), gripper_user_3()
6, 7, 8	User 4, User 5, User 6 (new in the 1.12 protocol)	Not handled by this version of the customer definitions

Note

You can leave a command that Bin Picking Studio never requests on None. The function is still generated, because execute_gripper calls it, but it is empty.

Note

If your gripper needs more than one digital output (a fieldbus write, a gripper URCap call or a sequence of steps), set the action to None and write your own logic in a Global Function of the program named gripper_attach, gripper_detach or gripper_user_1 to gripper_user_3. A function of the program is defined after the preamble and replaces the generated function with the same name.

3.2 BPS Program Nodes

Insert the nodes from the Toolbox of the program editor. Each node is one line in the program tree, shows what it does in its label and checks its own parameters. An incomplete node is marked, and you cannot start the program until it is complete.

Program node	Generated request	Result
BPS Initialize	pho_request_init(<start>, <end>, <vs>)	Sends the Start and End poses of every planned trajectory. Run it once for each vision system before the first scan.
BPS Scan	pho_request_scan, pho_request_trigger_scan, pho_run_loc_on_last_scan or pho_request_reuse_scan, then pho_wait_for_scan_completion()	Starts the scan, the localization and the path planning, and waits for the confirmation of the vision controller
BPS Trajectory	pho_request_trajectory(<vs>), then pho_receive_trajectory()	Requests and receives the trajectory for the next object. The received trajectory allows the next pick.
BPS Pick	pho_bin_picking(<start>, <vs>) or pho_bin_picking_simple(<start>)	Executes the received trajectory and controls the gripper at each waypoint
BPS Object Pose	pho_request_object_pose(<vs>)	Writes the pose of the next object to a program variable, for programs that plan their own motion
BPS Solution	pho_request_change_solution, pho_request_start_solution, pho_request_stop_solution, pho_request_running_solution or pho_request_available_solutions	Writes the running solution or the number of available solutions to a program variable
BPS Calibration	pho_calib_start, pho_calib_add_point(), pho_calib_save or pho_calib_stop	The calibration sequence. The Save step writes the calibration accuracy to a program variable.
BPS Vision System	pho_request_change_bbox, pho_request_change_env_state or pho_request_get_vs_status	The status request writes the processing state and the numbers of localized and pickable objects to program variables
BPS Pick Failed	pho_request_send_pick_failed(<vs>)	Tells the vision controller that the pick failed, so that it plans for the next object
BPS Comm Check	pho_request_comm_check()	Checks that the vision controller answers. It changes nothing.

Every node that uses a vision system has the options Default and Select. Default uses VISION_SYS_ID from the settings page, so if you change the default on the settings page, all programs that use it change. Select sets a fixed vision system number for this node. The multi-vision-system examples use this option.

For details about each request, see Action requests.

3.2.1 BPS Initialize

The Initialize request sends the Start and End poses to the vision controller. They are the first and the last waypoint of every planned trajectory. Select the Start pose and the End pose from the waypoints and pose variables of the program. Run the node once for each vision system before the first scan. Generated code:

pho_request_init(START_VS_1.p, END_VS_1.p, VISION_SYS_ID)

Note

For a waypoint, the node uses its pose part, so the generated call contains START_VS_1.p. Teach these waypoints with Tool_flange active (section 4.1).

3.2.2 BPS Scan

The Request field has four options:

• Scan and plan - pho_request_scan. The normal case: scan, localize and plan.

• Trigger scan only - pho_request_trigger_scan. Captures a scan for MultiView without localization.

• Localize on last scan - pho_run_loc_on_last_scan (deprecated name of the reuse-scan request).

• Reuse scan - pho_request_reuse_scan. Runs the localization of this vision system on the last scan.

Result defines whether the node waits for the confirmation of the vision controller. Keep it on Wait, unless the program must do something while the sensor works. With Continue, a later node, or a Script node with pho_wait_for_scan_completion(), collects the result. Generated code with Wait:

pho_request_scan(VISION_SYS_ID)
pho_wait_for_scan_completion()

Note

When Camera is set to Robot-mounted on the settings page, the Trigger scan only mode sends the flange pose with the request: pho_request_trigger_scan(VISION_SYS_ID, tcp_pose=get_actual_tool_flange_pose()).

3.2.3 BPS Trajectory

Requests and receives the planned trajectory for the next object. Request and receive is the normal setting. Request only leaves the receive to a later node or Script node. Generated code:

pho_request_trajectory(VISION_SYS_ID)
pho_receive_trajectory()

The node also has a Timeout field. If it is above 0, the value is passed to pho_receive_trajectory, but the library does not use it in this version.

Note

The received trajectory allows the next pick. If no trajectory was received since the last pick, pho_bin_picking halts the program with a program flow error.

3.2.4 BPS Pick

Executes the received trajectory segment by segment and controls the gripper at each waypoint that the vision controller marked. Start pose is the pose where the cycle starts. Pick selects the procedure of the customer definitions: With vision system generates pho_bin_picking, Single vision system generates pho_bin_picking_simple. Generated code:

pho_bin_picking(START_VS_1.p, VISION_SYS_ID)

Note

After the trajectory, the robot is at the End pose of the Initialize request and holds the object. Write the place routine yourself with native Move nodes. The examples contain a folder for it.

Note

If a pick fails (the object drops, or the gripper reports no part), report it with a BPS Pick Failed node, so that Bin Picking Studio plans for the next object and not for the same one.

3.2.5 BPS Object Pose

Asks for the pose of the next object instead of a planned trajectory and writes it to a program variable, which native Move nodes can use. Use this node in a cell that plans its own motion. Generated code:

pho_request_object_pose(VISION_SYS_ID)
global pho_object = pho_object_pose

3.2.6 BPS Solution

Changes, starts or stops a solution, reads the running solution, or reads the number of available solutions. You can type the solution ID or take it from a program variable. The change-solution example uses a variable to switch between two solutions. The running solution and the number of available solutions are written to program variables. Example of generated code:

pho_request_stop_solution()
pho_request_start_solution(SOLUTION_ID)

3.2.7 BPS Calibration

The four steps of a calibration sequence: Start, Add point, Save and Stop. Start needs the solution and the vision system. The other three steps need no input, because the vision controller reads the robot pose over RTDE. The Save step writes the calibration accuracy to a program variable. Example of generated code:

pho_calib_start(SOLUTION_ID, VISION_SYS_ID)
pho_calib_add_point()

Note

A calibration program moves the robot to nine or more taught poses and adds a point at each pose. Two of the examples do this (section 3.8).

3.2.8 BPS Vision System

Three requests that configure or query a vision system:

• Change bounding box - pho_request_change_bbox. Picks from a different region of the scene.

• Change environment state - pho_request_change_env_state. This request applies to the scene, not to a vision system, so the Vision System field is hidden.

• Get status - pho_request_get_vs_status. Writes the processing state and the numbers of localized and pickable objects to program variables.

Generated code for Get status:

pho_request_get_vs_status(VISION_SYS_ID)
global pho_vs_status = pho_process_state
global pho_localized = pho_num_localized
global pho_ready = pho_num_ready

3.2.9 BPS Pick Failed

Reports that the last pick failed, so that the vision controller plans for the next object. Put it in the failure branch of your gripper check. Generated code:

pho_request_send_pick_failed(VISION_SYS_ID)

3.2.10 BPS Comm Check

Asks the vision controller to answer and does nothing else. It is the quickest way to check the address, the port and the solution before you start a cycle. Generated code:

pho_request_comm_check()

3.3 Bin Picking Sequence

A complete bin picking cycle has four nodes:

1. BPS Initialize - once for each vision system, before the first scan

2. BPS Scan - scan, localize and plan, with Result set to Wait

3. BPS Trajectory - request and receive the trajectory for the next object

4. BPS Pick - execute the trajectory

The procedures called by the last node are in the customer definitions, which the settings page adds to the preamble:

Procedure	Description
pho_bin_picking(pho_start_position=pho_start_pose, vision_sys_id=PHO_VISION_ID_DEFAULT)	Description: Executes the trajectory received by the last pho_receive_trajectory(). It goes through the operation list of the trajectory, executes every trajectory segment and calls the gripper function that Bin Picking Studio requested at each waypoint. Do not edit this procedure. To change the motion settings, use the settings page (section 3.1.2). Input parameters: pho_start_position and vision_sys_id are accepted for compatibility with other Photoneo Robot modules, but they are not used. The procedure does not move the robot to the Start pose. Warning: The first waypoint of the trajectory is the Start pose sent with pho_request_init for this vision system. Make sure that the robot is in this pose before the pick. If it is not there, the streamed execution first moves it there with movej. Note: Set PATH PLANNING TYPE to PLAN JOINT AND LINEAR TRAJECTORIES on the Settings page of Bin Picking Studio.
pho_bin_picking_simple(pho_start_position=pho_start_pose)	Description: A minimal version for solutions with PATH PLANNING TYPE = PATH PLANNING OFF. It moves to pho_start_pose (the Start pose of the last Initialize request) with movej and then executes exactly four trajectory segments. It calls gripper_detach() before the grasp segment and gripper_attach() after it. It does not use the operation list.
gripper_attach()	Description: Generated from the Attach row of the gripper table. Typically used to attach the object at the Grasp waypoint. Usage: Called automatically when the Attach procedure is set on the waypoint of the grasping method that the robot has just reached.
gripper_detach()	Description: Generated from the Detach row of the gripper table. Typically used to release the object during placing. Usage: Called automatically when the Detach procedure is set on a waypoint of the grasping method. Usually, the robot program calls it at the place pose instead.
gripper_user_1(), gripper_user_2(), gripper_user_3()	Description: Generated from the User 1 to User 3 rows of the gripper table. For special operations, for example a blow-off pulse or a second vacuum zone. Usage: Called automatically when the matching User command is set on a waypoint of the grasping method.

Note

A trajectory can be executed only once. A received trajectory allows one pick, and the pick clears this permission. A BPS Pick without a preceding BPS Trajectory halts the program with a program flow error.

Note

Report a failed pick with a BPS Pick Failed node, so that Bin Picking Studio does not offer the same object again.

3.4 Validation and Program Tree Labels

Each node checks its parameters while you edit it. If a node is missing something (a Start or End pose on Initialize, a vision system number below 1, a solution ID below 1), it is marked as incomplete in the program tree, and PolyScope X does not run the program.

A complete node shows in its label what it does, so the program reads as a sequence of operations. Examples:

• Initialize default VS: START_VS_1 -> END_VS_1

• Scan, default VS, wait

• Trajectory of default VS, receive

• Pick default VS from START_VS_1

• Status of default VS -> pho_vs_status

3.5 Program Variables of the Nodes

A node that returns a result declares a program variable for it. You can use the result in native If, Assignment and Move nodes without a Script node. The variables are initialized at the start of the program, so you can read them before the node has run.

• pho_object - object pose, from BPS Object Pose

• pho_solution - running solution, and pho_solutions - number of available solutions, from BPS Solution

• pho_vs_status, pho_localized and pho_ready - processing state and numbers of localized and pickable objects, from BPS Vision System

• pho_calib_accuracy - calibration accuracy (µm), from the Save step of BPS Calibration

Note

These are the default names. If a name is already used in the program, the teach pendant creates a different name, and the node label shows the name that is used.

3.6 Result Variables of the Library

The library also has its own global variables, which you can read in any Script node or expression. They are the same as in the script variant, and the URCap does not change them. Info data values (see Info data) are stored in the unit in which they were sent, except pho_dimension_rot, which the library converts to degrees.

Variable	Set by	Meaning
PHO_ERR_CODE	every request	Response code of the last request (section 3.7)
PHO_OCCURRED_ERR	every request	True when the last request returned a non-zero response code
system_status	every request	Request that is being processed, for example 1 while scanning, 0 when waiting, 501 when disconnected
pho_object_pose	pho_request_object_pose	Cartesian pose of the localized object as a UR pose (p[x,y,z,rx,ry,rz], m, rad)
pho_start_pose, pho_end_pose	pho_request_init	Joint angles (rad) calculated from the Start and End poses and sent to the vision controller
pho_pick_allowed	pho_receive_trajectory	True while a received trajectory is not executed yet. pho_bin_picking clears it.
pho_tool_point_invariance	pho_receive_trajectory	Info data key 1 - tool point invariance index
pho_gripping_point_id	pho_receive_trajectory	Info data key 2 - gripping point ID
pho_gripping_point_invariance	pho_receive_trajectory	Info data key 3 - gripping point invariance index
pho_dimension_x, pho_dimension_y	pho_receive_trajectory, pho_request_object_pose	Info data keys 4, 5 - size of the object (mm). Only for solutions that measure the object.
pho_dimension_rot	pho_receive_trajectory, pho_request_object_pose	Info data key 6 - Z rotation of the object, converted to degrees by the library
pho_nn_label	pho_receive_trajectory	Info data key 7 - class label from AI localization
pho_max_z_height, pho_tilt	any response that contains keys 8, 9	Info data keys 8, 9 - stored as sent (mm, mrad). BPS does not send these keys. They are used by Locator Studio.
pho_num_localized	pho_request_get_vs_status	Info data key 12 - number of localized objects
pho_num_ready	pho_request_get_vs_status	Info data key 13 - number of objects ready for picking
pho_process_state	pho_request_get_vs_status	Info data key 14 - 0 when the processing is finished, 1 while the localization is running
pho_calib_acc	pho_calib_save	Info data key 10 - calibration accuracy (µm)
pho_camera_pose	pho_calib_save	Camera pose from the calibration result
pho_running_solution	pho_request_running_solution	Info data key 11 - ID of the solution that is running on the vision controller
pho_available_solutions	pho_request_available_solutions	List of available solution IDs (deprecated request)

3.7 Response Codes

PHO_ERR_CODE holds the response code of the last request. 0 means that the request completed. The library reports every other code with textmsg. Codes 3, 4, 6 and 255 also show a pop-up and stop the program. For the meaning of each code, see Error codes.

Code	Constant	Meaning
0	PHO_NO_ERROR	Request completed successfully
1	PHO_SERVICE_ERR	Service error on the vision controller
2	PHO_UNKNOWN_REQ	The vision controller does not know the request, or the robot received an unknown message
3	PHO_COM_FAILURE	Communication failure. The program stops.
4	PHO_BAD_DATA	Wrong data received. The program stops.
5	PHO_TIMEOUT	The response did not arrive within the timeout
6	PHO_LONG_TRAJECTORY	The trajectory is longer than the trajectory buffer (300 waypoints). The program stops.
7	PHO_BRAND_ID_ERR	The brand ID was rejected (new in 1.12)
8	PHO_BPS_IN_SIMULATION_MODE	Bin Picking Studio runs in simulation mode (new in 1.12)
200	PHO_UNKNOWN_ERR	Unknown bin picking error
201	PHO_PLANNING_FAILED	Path planning failed
202	PHO_NO_PART_FOUND	No object found
203	PHO_NOT_INITIALIZED	The vision system is not initialized. Run BPS Initialize first.
204	PHO_PART_LOST	The object was lost between localization and picking
218	PHO_EMPTY_SCENE	Empty scene
219	PHO_UNKNOWN_STATE	Unable to read the vision system pose (hand-eye vision systems; new in 1.12)
220	PHO_SCENE_NOT_AV	Scene state not found
221	PHO_SCENE_ACTIVE	Scene state already active
222	PHO_BBOX_ID_INVALID	Invalid bounding box ID (new in 1.12)
255	PHO_WRONG_BG_CONF	Wrong bin picking configuration. Details are in the Deployment console. The program stops.
450 - 459	PHO_INVALID_SOLUTION_ID … PHO_SOLUTION_FORBID	Solution errors: invalid solution ID, another solution running, start / stop error, solution incomplete, invalid brand ID, solution already running, operation forbidden
460 - 469	PHO_INVALID_VS … PHO_CALIB_NOT_ALLOWED	Calibration errors: invalid vision system, calibration already running / not running, start / stop error, calibration disabled, not enough points, error too high, scanner not available, calibration not allowed
501	PHO_DISCONNECTED	Value of system_status when the connection to the vision controller is down

3.8 Example Programs

The fourteen example programs are the fourteen programs of the script variant, rebuilt with the BPS nodes. They have the same waypoints, the same motion and the same error handling. Each request is replaced by the node that generates it, and the two script blocks and the gripper functions are replaced by the settings page.

Example program	Description
pho_main_basic_urc	The basic bin picking template: Initialize, Scan, Trajectory and Pick in a loop. The place routine is for you to complete. Start with this program.
pho_main_basic_hand_eye_urc	The same cycle with a robot-mounted sensor. The scan is sent from the taught Scanning pose, and the vision controller reads the flange pose over RTDE. The example uses Scan and plan, so it works with Camera set to Fixed.
pho_main_basic_multi_vs_urc	Two vision systems. Each one is initialized with its own Start and End poses, and they are picked in turn.
pho_main_change_bb_urc	Switches the bounding box between scans with the BPS Vision System node.
pho_change_enviroment_urc	Switches the environment (scene) state, for a cell in which fixtures move.
pho_main_change_solution_urc	Reads the running solution. If it is a different one, stops it and starts the required solution before picking. Changes the solution after each pick.
pho_main_get_object_pose_urc	Asks for the pose of the next object instead of a planned trajectory and moves to it with native Move nodes.
pho_main_get_status_urc	Reads the vision system status (processing state, numbers of localized and pickable objects).
pho_main_reuse_scan_urc	Runs the localization of a second vision system on the scan of the first one, instead of scanning again.
pho_multiview_static_urc	Three trigger scans from three taught poses, then one localization over all of them. Camera is set to Robot-mounted.
pho_multiview_dynamic_urc	Dynamic MultiView, which triggers scans while the robot moves. Requires a MotionCam-3D. Camera is set to Robot-mounted.
pho_calibration_basic_urc	The nine-point calibration sequence, with Add point steps sent from the robot.
pho_calibration_auto_urc	The same sequence with Start, Save and Stop also sent from the robot, for automatic recalibration.
pho_calib_basic_hand_eye_urc	The calibration sequence for a robot-mounted sensor.

For a detailed description of each example, see section 3.7 of the script variant guide.

Note

Each example shows the script program it was generated from in its program description. The teach pendant shows the description on the Programs page of the System Manager.

4. Runtime

When the solution is fully configured on the vision controller, finish the remaining steps on the robot side and run the first bin picking cycle.

4.1 Teach Positions

After you open pho_main_basic_urc.urpx or another example, touch up the local poses of the program: the Scanning pose, to which the robot moves before a scan, and the poses of the place routine (Before_Place, Place, Deaprr_Place). The image below shows them in the script variant of the program. The URCap example uses the same poses.

You must also define the Start and End poses for every vision system of the solution. They are the first and the last waypoint of every planned trajectory: the vision controller plans from the Start pose to the grasp, and from the grasp to the End pose.

To set them, open the pos function of the Positions module on the right side of the program, select the waypoint START_VS_1 or END_VS_1, move the robot there and teach the waypoint:

Note

Do not rename these waypoints. The BPS Initialize node refers to them by name, and its label shows which waypoints it uses. If you rename a waypoint, select it again in the node.

Note

Teach these waypoints with the Tool_flange end effector active, and make sure that it is active when the program runs. A waypoint is a pose of the active TCP. If you teach it with another end effector, the robot moves to a different position at runtime.

4.2 Gripper Commands

With the URCap, the gripper functions are not functions of the program. The URCap generates them from the gripper table of the settings page (section 3.1.3). Set the output, the value and the settle time of each command there.

On the Grasping Methods page of Bin Picking Studio, you select which gripper command is requested at which waypoint of the trajectory:

Note

Check the gripper table after you import an example program. The example brings the outputs it was saved with. In pho_main_basic_urc, Attach and Detach use Controller DO 0 with a settle time of 0 ms. In the other examples, all actions are set to None. These are probably not the outputs of your gripper.

4.3 Runtime Prerequisites

Do a final check before you start the bin picking program on the robot.

Make sure that:

• The bin picking solution is correctly configured on the vision controller.

• The network setup on the robot side is complete, and the same vision controller address is entered on the settings page.

• RTDE is enabled and the Robot State Server shows CONNECTED on the Deployment page.

• All vision systems in the solution are calibrated.

• The Start and End poses of all vision systems are touched up.

• All local poses in the main program are touched up.

• The gripper table matches the outputs of your gripper, and the gripper is tested.

• The Tool_flange end effector is active.

4.4 Running the pho_main_basic_urc Program

Deploy your solution. Until the robot program connects, the Deployment page shows the Action Request Client (Robot) status as DISCONNECTED:

Note

Before you run the program for the first time, we strongly recommend that you decrease the Speed slider on the teach pendant to 20%.

Press Play. The preamble connects to the vision controller, so the Action Request Client and Robot State Server status changes to CONNECTED as soon as the program starts:

If there is a pickable object in the scene and the robot has received the trajectory for it, the robot starts to move towards the object. Keep your hand on the emergency stop, watch the first approach and check that the path is the planned one.

If the robot stops too far from the object or pushes it too deep, change the settings on the Tool Point or Gripping Point page of Bin Picking Studio.

If the trajectories look fine, set up your own placing routine and slowly increase the speed back to 100%.

You have successfully deployed the Photoneo Robot module for Universal Robots with the Bin Picking Studio URCap.

5. Robot Module Update

To update the Robot module to a version that matches your Bin Picking Studio version, install the new URCap and check the settings page:

1. Note your settings. Write down the vision controller address, the motion parameters and the gripper table, or take a screenshot of the settings page. You need them if the new URCap version resets them.

2. Install the new URCap. Install the new .urcapx file as described in section 2.3. It replaces the older version of the same URCap, and the system reloads.

3. Check the settings. Open the settings page and compare the three sections with your notes.

4. Check the API changes. Read the API changes of the new Robot module version. When you open a program, nodes with changed parameters are updated, and the node labels show what they do. Check the labels of the Photoneo lines in every program after the update.

5. Import new examples (optional). Import the new example programs as described in section 2.4. They bring their own settings, so import them before you fine-tune the settings page, not after.

Note

The URCap version is shown on the URCaps page of the System Manager. The version of the embedded library is in the header of the preamble: Description: Zebra Technologies script for flexible_communication v.1.12 library. The brand ID is UNIVERSAL_ROBOTS/v1.12.0. URCap 1.12.1 still sends this brand ID, because the vision controller rejects brand IDs that it does not know.

When you open a program saved with URCap 1.12.0, the settings page gets the new Trajectory speed and Trajectory acceleration defaults, and the old servo values are dropped.

For the changes in the communication interface, see Migration from BPS 1.11.x to BPS 1.12.x.

6. Version and Brand ID

Item	Value
URCap	Bin Picking Studio 1.12.1 (bin-picking-studio-1.12.1.urcapx, vendor Photoneo)
Embedded library	photoneo_common_X.script v.1.12
Bin Picking Studio	1.12
Brand ID	UNIVERSAL_ROBOTS/v1.12.0
Action Request Server port	11003
Robot state (RTDE) port	30004
PolyScope X	10.12.1 or higher